Refactor README: move detailed docs to separate guides#74
Merged
Conversation
Compress README from 575 to 185 lines. Move detailed reference content to docs/ while keeping the README focused on quick start and tool overview. New files: - docs/client-setup.md: platform-specific setup guides - docs/access-control.md: read-only, disable-delete, dynamic tool list, per-request auth - docs/development.md: dev setup, testing, MCP Inspector - docs/troubleshooting.md: common issues and fixes Fix OUTLINE_DYNAMIC_TOOL_LIST default documented as true/enabled in 3 places — actual default is false (disabled). https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
Better reflects the content — server configuration details for permissions, tool filtering, and authentication. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
Frame uvx as the default example path, not a hard requirement. Link to the existing pip section as an alternative. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
Include OUTLINE_API_URL with // Optional comment instead of explaining it separately in prose. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
Show inline header snippet so users don't have to navigate to configuration.md for the basic pattern. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
Combine into a single "Multi-User Setup (HTTP)" section in configuration.md. Per-request auth explains the mechanism, dynamic tool list builds on top as optional filtering. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
The parent "Multi-User Setup (HTTP)" section already provides the context; the bullets were restating it. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
SSE is not specifically for web clients; drop the annotation to keep the transport list consistent. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
Returns an error to the user after 3 failed attempts. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
Replace "per-request auth/authentication" with "per-user Outline API keys" and "multi-tenant" with "multi-user" across all documentation. This better describes the feature (each user brings their own Outline API key) and leaves room for future MCP-level authentication. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
Comment out automatic triggers for claude.yml and claude-code-review.yml. Keeps workflow_dispatch so they can still be triggered manually if needed. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
- Fix `uv sync --extra dev` → `uv sync --group dev` in README, CONTRIBUTING, and development docs. The project uses [dependency-groups] not [project.optional-dependencies], so --extra dev fails. - Add missing OUTLINE_VERIFY_SSL to README config table (was only documented in CLAUDE.md and .env.example). - Update .env.example: "per-request" → "per-user" for consistency with earlier terminology change. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
Mark as Yes* since stdio has no HTTP headers — the env var is the only way to authenticate. SSE/streamable-http can use the x-outline-api-key header per-user instead. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
Replace raw `pytest tests/ -v` with `uv run poe test-unit` to match the rest of the docs and include coverage reporting. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
The enhancement roadmap is outdated — many items are completed or no longer relevant. GitHub Issues is a better place to track future work. Removing to avoid confusion. https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?
This PR reorganizes the README to improve readability and maintainability by extracting detailed documentation into separate guide files:
docs/client-setup.md: Client-specific installation instructions (Claude Desktop, Cursor, VS Code, Cline, Docker, pip)docs/configuration.md: Detailed configuration options (read-only mode, disable-delete, dynamic tool list, per-request auth)docs/development.md: Development setup, testing, E2E tests, MCP Inspector, and architecture notesdocs/troubleshooting.md: Common issues and solutionsThe README is now streamlined with:
This makes the README more scannable while preserving all documentation through cross-references.
Checklist
uv run pre-commit installand committed with hooks enableduv run pytest tests/ -v)https://claude.ai/code/session_01D39J19eFevHGtkSianfKxh